docs/development/Building in Windows 10 or 11 with Linux Subsystem.md

   1 # Building in Windows 10 with Linux subsystem [Recommended]
   2
   3 Linux subsystem for Windows 10 is probably the simplest way of building INAV under Windows 10.
   4
   5 ## Setting up the environment
   6
   7 Enable WSL:
   8 run `windows features`
   9 enable `windows subsytem for linux`
  10 reboot
  11
  12
  13 Install Ubuntu:
  14 1.  Go to Microsoft store https://www.microsoft.com/en-gb/store/b/home
  15 1.  Search and install most recent Ubuntu LTS version
  16 1.  When download completed, select `Launch Ubuntu`
  17 1.  When prompted enter a user name and password which you will need to remember
  18 1.  When complete, the linux command prompt will be displayed
  19
  20 NOTE: from this point all commands are entered into the Ubunto shell command window
  21
  22 Update the repo packages:
  23 -  `sudo apt update`
  24
  25 Install Git, Make, gcc and Ruby
  26 -  `sudo apt-get install git make cmake ruby`
  27
  28 Install python and python-yaml to allow updates to settings.md
  29 -  `sudo apt-get install python3`
  30
  31 ### CMAKE and Ubuntu 18_04
  32
  33 To run  `cmake` in the latest version you will need to update from Ubuntu `18_04` to `20_04`. The fastest way to do it is to uninstall current version and install `20_04` for Microsoft Store [https://www.microsoft.com/store/productId/9N6SVWS3RX71](https://www.microsoft.com/store/productId/9N6SVWS3RX71)
  34
  35 ## Downloading the INAV repository (example):
  36
  37 Mount MS windows C drive and clone INAV
  38 1.   `cd /mnt/c`
  39 2.   `git clone https://github.com/iNavFlight/inav.git`
  40 3.   `git checkout 6.1.1` (to switch to a specific release tag, for this example INAV version 6.1.1)
  41 4.   `git checkout -b my-branch` (to create own branch)
  42
  43 You are ready!
  44 You now have a folder called inav in the root of C drive that you can edit in windows
  45
  46 ### If you get a cloning error
  47
  48 On some installations, you may see the following error:
  49 ```
  50 Cloning into 'inav'...
  51 error: chmod on /mnt/c/inav/.git/config.lock failed: Operation not permitted
  52 fatal: could not set 'core.filemode' to 'false'
  53 ```
  54
  55 You can fix this with by remounting the drive using the following commands
  56 1. `sudo umount /mnt/c`
  57 2. `sudo mount -t drvfs C: /mnt/c -o metadata`
  58
  59 ## Building (example):
  60
  61 For detailed build instrusctions see [Building in Linux](Building%20in%20Linux.md)
  62
  63 Launch Ubuntu:
  64 Click Windows Start button then scroll and lauch "Ubuntu"
  65
  66 Building from Ubuntu command line
  67
  68 `cd /mnt/c/inav`
  69
  70 Do it onece to prepare build environment
  71 ```
  72 mkdir build
  73 cd build
  74 cmake ..
  75 ```
  76
  77 Then to build
  78 ```
  79 cd build
  80 make MATEKF722
  81 ```
  82
  83 ## Updating the documents
  84 ```
  85 cd /mnt/c/inav
  86 python3 src/utils/update_cli_docs.py
  87 ```
  88
  89 ## Flashing:
  90 Launch windows configurator GUI and from within the firmware flasher select `Load firmware[Local]`
  91 Hex files can be found in the folder `c:\inav\build`
  92
  93 ## Troubleshooting
  94
  95 ### Syntax error: "(" unexpected
  96
  97 ```
  98 dzikuvx@BerlinAtHome:/mnt/c/Users/pspyc/Documents/Projects/inav/build$ make MATEKF722SE
  99 Generating MATEKF722SE/settings_generated.h, MATEKF722SE/settings_generated.c
 100 /bin/sh: 1: Syntax error: "(" unexpected
 101 make[3]: *** [src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/build.make:63: src/main/target/MATEKF722SE/MATEKF722SE/settings_generated.h] Error 2
 102 make[2]: *** [CMakeFiles/Makefile2:33607: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/all] Error 2
 103 make[1]: *** [CMakeFiles/Makefile2:33290: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.dir/rule] Error 2
 104 make: *** [Makefile:13703: MATEKF722SE] Error 2
 105 ```
 106
 107 This error can be triggered by a Windows PATHs included in the Linux Subsystem. The solution is:
 108
 109 #### For WSL V1 - Flags set as 7 by default
 110
 111 1. Open Windows RegEdit tool
 112 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 113 1. Change `Flags` from `7` to `5`
 114 1. Restart WSL and Windows preferably
 115 1. `cd build`
 116 1. `cmake ..`
 117 1. `make {TARGET}` should be working again
 118
 119 #### For WSL V2 - Flags set as 0x0000000f (15) by default
 120 1. Open Windows RegEdit tool
 121 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 122 1. Change `Flags` from `f` to `d`, it is stored as Base Hexadecimal
 123 1. Restart WSL and Windows preferably
 124 1. `cd build`
 125 1. `cmake ..`
 126 1. `make {TARGET}` should be working again
 127
 128 #### Or, for either version
 129 1. In the Linux Subsystem, `cd /etc/`
 130 2. Create a new file with `sudo nano wsl.conf`
 131 3. Enter the following in to the new file:
 132 ```
 133 [Interop]
 134 appendWindowsPath=false
 135 ```
 136 4. Save the file by holding `Ctrl` and pressing `o`
 137 5. Press `Enter` to confirm the wsl.conf filename.
 138 6. Hit `Ctrl`+`x` to exit nano
 139 7. Restart WSL and Windows preferably
 140 8. `cd build`
 141 9. `cmake ..`
 142 9. `make {TARGET}` should be working again
 143
 144 ### Building targets is very slow
 145 I was pretty shocked when my new i7 -10750 laptop took 25 minutes to build a single target. My old i3-4030 could do the same job in about 2.5 minutes. If you're also suffering from slow builds. Open an elevated PowerShell window and type
 146 ```
 147 wsl -l -v
 148 ```
 149 If you see your Linux distribution is using WSL 2, this is the problem. WSL 2 is quicker than WSL 1 for a lot of things. However, if your files are on a windows mounted drive in Linux, it is extremely slow. There are two options:
 150 1. Put your files on the Linux file system
 151 2. Change to WSL 1
 152
 153 #### Using the Linux file system (recommended)
 154 To use the Linux file system, make sure the distro is running. Open File Explorer and navigate to `\\wsl$`. In that path you will find your distros listed. At this point, map a network drive to your distro. Inside the distro, you can find your home directory at `/home/~username~/`. Create your GitHub folders here.
 155
 156 If after this you have problems with writing to the directories from within VSCode. Open the application for your distro and type
 157 ```
 158 sudo chown -R ~username~ GitHub
 159 ```
 160 `~Username~` is your root distro user that you created and `GitHub` should be the root folder for your GitHub repositories.
 161
 162 #### To switch back to WSL 1
 163 To do this, in the elevated PowerShell window, you can see the name of your distro. Mine is **Ubuntu-20.04**, so I'll use that in this example. Simply type
 164 ```
 165 wsl --set-version Ubuntu-20.04 1
 166 ```
 167 and your distro will be converted to WSL 1. Once finished, reboot your system. Next time you compile a build, it will be faster.